Location#

The global Location API provides access to the device’s geographic location, including one-time location retrieval, reverse geocoding, user-driven location selection via map, accuracy control, and permission checking for widgets.

#Overview

This API allows you to:

• Request the device's current location
• Select a location manually using a map interface
• Reverse geocode latitude and longitude to address details
• Adjust location accuracy settings
• Check location access status for widgets

Note: This is a global API and does not require import.

#API Reference

#Location.isAuthorizedForWidgetUpdates(): Promise<boolean>

Checks whether widgets have permission to receive location updates.

const isAuthorized = await Location.isAuthorizedForWidgetUpdates()
if (!isAuthorized) {
  console.log("Widget location access is not authorized.")
}

#Location.setAccuracy(accuracy: LocationAccuracy): Promise<void>

Sets the desired accuracy level for location retrieval. Higher accuracy may increase battery usage and wait time.

#Parameters

await Location.setAccuracy("hundredMeters")

#Location.requestCurrent(options?: { forceRequest?: boolean }): Promise<LocationInfo | null>

Requests the user's current location once. May trigger a permission prompt if not previously granted.

By default, if a cached location is available, it will be returned immediately. If no cached location exists, a new request will be made. To force a new location retrieval even if a cached value exists, pass { forceRequest: true }.

#Parameters

const location = await Location.requestCurrent({ forceRequest: true })
if (location) {
  console.log("Latitude:", location.latitude)
  console.log("Longitude:", location.longitude)
  console.log("Timestamp:", location.timestamp)
}

#Location.pickFromMap(): Promise<LocationInfo | null>

Opens the built-in map interface to allow the user to manually select a location.

const selected = await Location.pickFromMap()
if (selected) {
  console.log("User selected:", selected.latitude, selected.longitude)
}

#Location.reverseGeocode(options): Promise<LocationPlacemark[] | null>

Converts latitude and longitude into human-readable place information such as street, city, and country.

#Parameters

const placemarks = await Location.reverseGeocode({
  latitude: 51.5074,
  longitude: -0.1278,
  locale: "en-GB"
})

if (placemarks?.length) {
  const place = placemarks[0]
  console.log("City:", place.locality)
  console.log("Country:", place.country)
}

#Types

#LocationAccuracy

Specifies the desired accuracy of location data:

type LocationAccuracy =
  | "best"
  | "tenMeters"
  | "hundredMeters"
  | "kilometer"
  | "threeKilometers"

#LocationInfo

Represents a geographic coordinate with timestamp:

type LocationInfo = {
  /**
   * The latitude in degrees.
   */
  latitude: number
  /**
   * The longitude in degrees.
   */
  longitude: number
  /**
   * Timestamp of when the location was recorded, in milliseconds since epoch.
   */
  timestamp: number
}

#LocationPlacemark

Represents a human-readable description of a geographic coordinate, typically returned by reverse geocoding. Includes structured location details such as city, country, and street.

type LocationPlacemark = {
  location?: LocationInfo
  region?: string
  timeZone?: string
  name?: string
  thoroughfare?: string
  subThoroughfare?: string
  locality?: string
  subLocality?: string
  administrativeArea?: string
  subAdministrativeArea?: string
  postalCode?: string
  isoCountryCode?: string
  country?: string
  inlandWater?: string
  ocean?: string
  areasOfInterest?: string[]
}

#Field Descriptions

#Example Usage

#Reverse Geocode

const placemarks = await Location.reverseGeocode({
  latitude: 40.7128,
  longitude: -74.0060,
  locale: "en-US"
})

if (placemarks?.length) {
  const place = placemarks[0]
  console.log("Country:", place.country)
  console.log("City:", place.locality)
  console.log("Street:", place.thoroughfare, place.subThoroughfare)
  console.log("Full Name:", place.name)
  console.log("Postal Code:", place.postalCode)
  console.log("Points of Interest:", place.areasOfInterest?.join(", "))
}

#Address Formatter (Helper)

function formatAddress(p: LocationPlacemark): string {
  return [
    p.country,
    p.administrativeArea,
    p.locality,
    p.subLocality,
    p.thoroughfare,
    p.subThoroughfare
  ].filter(Boolean).join(", ")
}

#Best Practices & Use Cases

• Use areasOfInterest and name to display user-friendly place names.
• Use postalCode, locality, and administrativeArea for autofill and geotagging.
• Use timestamp to determine freshness of location data.
• Use timeZone for localizing time-based features.
• Set location accuracy before calling requestCurrent for optimal precision.
• Always check widget permissions via isAuthorizedForWidgetUpdates().

#Notes

• Reverse geocoding may return multiple results. Use the first placemark for best relevance.
• If location retrieval fails, null is returned.
• When forceRequest is false or omitted, cached location may be used for faster results.
• In widgets, location access may be restricted. Always verify permissions explicitly.